import { Meta, Status, Props, Story } from '../../../../.storybook/components';
import * as Stories from './Anchor.stories';

<Meta of={Stories} />

# Anchor

<Status variant="stable" />

The Anchor component is used to display a link or button that visually looks like a hyperlink.

<Story of={Stories.AsLink} />
<Props />

## Component variations

### As button

If necessary, an Anchor can be rendered as a semantic `<button>` element. It will look like an Anchor but behave like a button.

Bear in mind that this might lead to confusion for some users, since the expectation is that the Anchor should behave like a link (i.e. it should navigate), and conversely, something that behaves like a button (i.e. that performs an action) should look like a button.

<Story of={Stories.AsButton} />

## Accessibility

The Anchor component is most commonly used to render a hyperlink. Links are one of the most important elements in HTML. They bring the "H" in "<abbr title="HyperText Markup Language">HTML</abbr>", since hypertext without links is mostly just text.

Note that the following guidelines apply to hyperlinks generally, and not only those rendered by the Anchor component.

### Best practices

#### Links should be focusable

All links must be focusable in order to be usable by all users. A focus outline should also be visible so that keyboard users know where they are when tabbing through the page.

The Anchor component is focusable by default and comes with an accessible focus outline. Do not remove it!

#### Focus order should follow a logical reading order

As detailed in [2.4.3: Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order), focus order on a page should follow a logical reading order.

Keep in mind that reading order may not be the same for sighted and screen-reader users:

- For a sighted user, reading order is influenced by styles. If an element is visually placed above another, or is emphasized through the use of color or typography, it is more likely to be read first. Therefore, if interactive, it is generally expected to receive focus first.
- For a a screen reader user, reading order is determined by the DOM. Irrespective of where elements are placed visually, what matters is their position in the DOM. What follows is that the DOM itself should be ordered logically: think about whether your interface is still understandable without styles.

#### Links should rarely open in new tabs or windows

A link that opens in a new tab or window can confuse users, especially those relying on assistive technology. [Links should only open in new tabs or windows when necessary](https://www.w3.org/WAI/WCAG21/Techniques/general/G200).

For example, if there is a link to terms and conditions above a form's submit button, and form progress would be lost if the link is visited before submission, it makes sense to open the link in a new tab to preserve the user's progress. It is also a good practice to explicitly warn that the link will open in a new tab, using iconography and/or plain text ("link opens in a new tab").

In contrast, imagine that _cats.com_ features a link to _dogs.com_. It is not a good practice to make _dogs.com_ open in a new tab. Instead, trust users to know how to open the link in a new tab themselves, or how to navigate back to _cats.com_ later, if they so desire.

#### Links should have a clear purpose

The purpose of a link should be easy to determine by users. Ideally, a link's text should define the content of the linked resource, much like a heading's text defines the content of its section. The link's text could also match the destination page's name, to give users confirmation that they arrived in the right place after navigating.

[2.4.4: Link Purpose (In Context)](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html) states that link purpose must be inferrable from the link's context, i.e. the same paragraph, list item, or table cell as the link. So for example, a user should be able to understand what a link does by reading the surrounding paragraph.

A best practice is to go even further, and attempt to make link purpose understandable even out of context, by the link text only. The reason behind this best practice is primarily that it's common for screen reader users to find their way on the web by pulling up a list of links on a page. The WCAG level AAA success criterion [2.4.9: Link Purpose (Link Only)](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-link-only) makes this a requirement.

_Note: while it is tempting at this point to add visually hidden text (or an `aria-label`) to a link to make its purpose clear out of context for screen reader users, we recommend against it: voice control users may not be able to target the link if its accessible name doesn't match its visible text._

#### Links to the same resource should be named consistently

If there are several links to the same resource on a page, they should have a consistent link text, ideally identical.

[3.2.4: Consistent Identification](https://www.w3.org/WAI/WCAG21/Understanding/consistent-identification) requires that components with the same functionality are named consistently. While the success criterion is primarily intended for functional components found on multiple pages, such as a search feature, it is a good practice to also apply it to link text.

It will make link purpose more predictable, benefiting people with cognitive limitations as well as screen reader users going through a list of the page's links.

Similarly, links with the same text should ideally link to the same resource. For example, a "Read more" link on each article in a list doesn't help differentiating the links in a screen reader's list of links. Instead, it is better to place the links on each article's title, for example.

#### Keep links blue and underlined

[Links have been blue and underlined since 1993](https://blog.mozilla.org/en/internet-culture/deep-dives/why-are-hyperlinks-blue/), so a good practice is to meet user expectations by sticking to this convention as much as possible. Likewise, avoid blue and underlined text that is _not_ a link.

If links are differentiated from text by color alone, they must have a contrast ratio of at least 3:1 with surrounding text to meet [1.4.1: Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color). However, keep in mind that a best practice is to never rely on color alone in interfaces, since some users do not perceive color at all (achromatopsia). In short: keep links underlined.

#### Avoid using block links

Block links, a.k.a. clickable cards, refer to links around entire block elements, such as an article card with an image, title and excerpt.

While this is valid markup since HTML5, block links are handled in wildly different ways by assistive technologies, at best reading the entire block element without structure before announcing the role, "link", and at worst ignoring (parts of) the link altogether.

There are creative ways to work around this behavior, with and without recourse to JavaScript, that others have explored in in-depth articles:

- [_Cards_ by Heydon Pickering](https://inclusive-components.design/cards/)
- [_Block Links, Cards, Clickable Regions, Rows, Etc._ by Adrian Roselli](https://adrianroselli.com/2020/02/block-links-cards-clickable-regions-etc.html)

However, other accessibility issues can persist beyond what the screen reader behavior, such as:

- if there is no visual cue that the entire element is a link, the interaction may not be obvious to some users
- users with motor disabilities (e.g. Parkinson's), who could accidentally click the link when intending to scroll on mobile devices
- voice control users may find it difficult to interact with the link

Generally, because of the complexity surrounding this pattern, we recommend against using block links. Instead, use the Anchor component explicitly inside a card, for example. If using block links anyways, make sure to manually test your interface with the most common screen reader/browser combinations, as well as voice control software.

### Resources

#### Test your page's keyboard interactivity

Tab through your interface and verify that all links receive focus in a logical order, as described in the "Best practices" section. Also ensure that all focusable elements have a visible outline when focused.

#### Verify your UI without color

Simulate vision deficiencies or desaturate your page, and verify that visual cues beyond color are helping users identify links.

- [Simulate vision deficiencies using Firefox](https://developer.mozilla.org/en-US/docs/Tools/Accessibility_inspector/Simulation)
- [Simulate vision deficiencies using Chrome](https://developer.chrome.com/blog/new-in-devtools-83/#vision-deficiencies)
- Desaturate a page using [Wave](https://wave.webaim.org/) (under Contrast, "Desaturate page")

#### Test your page using a screen reader

[Test your page using a screen reader](https://webaim.org/articles/screenreader_testing/) like JAWS (Windows), NVDA (Windows, Linux) or VoiceOver (macOS).

This is particularly valuable if using block links (refer to the "Avoid using block links" section above), or links with punctuation or structure (such as line breaks, or links around an icon and text).

You can also view your links using your screen reader's links list feature. With VoiceOver for example, open the rotor (VO+U) and use the left/right arrow keys to find the links list.

#### Related WCAG success criteria

- 1.4.1: [Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color)
- 2.4.3: [Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order)
- 2.4.4: [Link Purpose (In Context)](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context.html)
- 2.4.9: [Link Purpose (Link Only)](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-link-only) (AAA)
- 3.2.4: [Consistent Identification](https://www.w3.org/WAI/WCAG21/Understanding/consistent-identification)
